"""
Copyright 2009 Texas A&M University
 
Licensed under the Apache License, Version 2.0 (the "License"); you may not use 
this file except in compliance with the License. You may obtain a copy of the 
License at

http://www.apache.org/licenses/LICENSE-2.0
  
Unless required by applicable law or agreed to in writing, software distributed 
under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR 
CONDITIONS OF ANY KIND, either express or implied. See the License for the 
specific language governing permissions and limitations under the License. 
"""

import zope.interface



class IStorage(zope.interface.Interface):
    def getName(self):
        """Return a name for the Storage"""
  
    def action(self, instance):
        """This method performs an add/update operation on instance(s) as
        necessary.
        
        Keyword arguments:
        instance -- Either a single object providing the 
          meercat.interfaces.IInstance interface or an iterable collection of 
          objects providing the meercat.interfaces.IInstance interface. Required
        
        If the instance argument is not a meercat.interfaces.IInstance, a 
        zope.interface.exceptions.DoesNotImplement exception should be raised.
        """
    
    def merge(self, destination, remove):
        """This method merges the remove object into the destination object.
        This operation is used when de-duping records. All of the instances from
        the remove resource should be appended to the destination object and then
        the remove object should be marked as inactive.
        
        Keyword Arguments:
        destination -- This must be an object that provides the 
          meercat.interfaces.IMutableResource interface.
        remove -- This is either an object providing the 
          meercat.interfaces.IResource interface or an iterable collection of 
          objects that provide the meercat.interfaces.IMutableResource interface.
        
        If the destination argument is not a meercat.interfaces.IResource, a 
        zope.interface.exceptions.DoesNotImplement exception should be raised.
        
        If the remove argument is not a meercat.interfaces.IMutableResource or a 
        collection of them, a zope.interface.exceptions.DoesNotImplement 
        exception should be raised.
        """
    
    def getResources(self, **kwargs):
        """Search through the storage and return an iterable collection of
        objects providing the meercat.interfaces.IResource interface.
        
        Keyword arguments:
        limit -- If provided, limit the resulting collection to this size
        offset -- If provided, only provide results after this offset into the 
          result set
        from_date -- If provided, limit results to those added/updated after 
          this datetime.datetime object
        until_date -- If provided, limit results to those added/update before
          this datetime.datetime object
        source -- If provided, limit the results to those that have instances
          coming from this source
        identifier -- If provided, only return the resource that matches this
          identifer
        inactive -- If false, limit results to 'active' resources
        """
  
    def getInstances(self, **kwargs):
        """Search through the storage and return an iterable collection of
        objects providing the meercat.interfaces.IInstance interface.
        
        Keyword arguments:
        limit -- If provided, limit the resulting collection to this size
        offset -- If provided, only provide results after this offset into the 
          result set
        from_date -- If provided, limit results to those added/updated after 
          this datetime.datetime object
        until_date -- If provided, limit results to those added/update before
          this datetime.datetime object
        source -- If provided, limit the results to those coming from this 
          source
        identifier -- If provided, only return the resource that matches this
          identifer
        inactive -- If false, limit results to 'active' resources
        """
    
    def getResourceCount(self):
        """Return the number of resources in the storage """
    
    def getInstanceCount(self):
        """Return the number of instances in the storage """

class IPersistent(zope.interface.Interface):
    """This interface marks objects as being capable of being stored."""
    
    def save(self):
        """Save this object in permanent storage """